Vega-Lite文档: 01_view

视图规范View

Offical documentation

视图规范`View`

single view
layer
facet
concat
repeat

属性

所有的ViewSpec都支持以下属性:

属性	类型	描述
name	String	图的名字
description	String	描述信息, 注释
title	`Text\|TitleParams`	图的标题
data	`Data\|Null`	必需项, 如果不提供数据, 则从上级表继承
transform	`Transform[]`	数据转换规则列表
params	`TopLevelParameter[]`	映射用户输入和Data的参数列表

此外, layer, facet, concat, repeat等还支持resolve属性:

属性	类型	描述
resolve	Resolve	设置Scale, axis, legend分辨率

facet, concat, repeat等支持的属性:

属性	类型	描述
align	String/Object	按行/列对齐grid, 支持的参数为`all, each, none`: `none` => flow layout; `each` => 可自定义每个subview的大小; `all` => (默认值) 每个subview大小都一样; 也可以`}{"row": string, "column": string}`的形式自定义行列的对齐规则. (这个属性类似于ggplot中facet里的scale: free freex, freey)
bounds	String	限制子图大小, 可选参数`full, flush`.
center	Boolean/Object	子图是否居中, 也可以用`{"row": boolean, "column": boolean}`的形式指定行/列是否居中
spacing	Number/Object	子图间距大小(像素). 也可用`{"row": number, "column": number}`的形形式独立设定行/列, 默认情况下, 直接继承view composition设置中的值(默认是20)

最顶层的视窗(Top-level specifications)还支持以下属性:

属性	类型	描述
`$schema`	String	设置Vega-Lite的纲要, 一般不会改这个属性, 直接用`https://vega.github.io/schema/vega-lite/v5.json`
background	Color/ExprRef	CSS颜色属性, 配置背景色, 默认: "white"
padding	Number/Object/ExprRef	默认图的padding(像素), 类似CSS的规则, 如果是一个数字, 则应用四边, 如果是json对象,则应该遵循以下格式`{"left":5, "top":5, "right":5, "bottom":5}`, 默认值5
autosize	String/AutoSizeParams	设置如何决定图的大小, 可选参数`pad, fit, none`. 默认是`pad`
config	Config	Vega-Lite的配置参数
unsermeta	Object	metadata, 不知道干啥用的

单视图

一个基本单视图大概包含如下属性:

json

{
    // Properties for top-level specification
    "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
    "background": ...,
    "padding": ...,
    "autosize": ...,
    "config": ...,
    "usermeta": ...,
    // Properties for any specifications
    "title": ...,
    "name": ...,
    "description": ...,
    "data": ...,
    "transform": ...,
    // Properties for any single view specifications
    "width": ...,
    "height": ...,
    "mark": ...,
    "encoding": {
        "x": {
            "field": ...,
            "type": ...,
      ...
        },
        "y": ...,
        "color": ...,
    ...
    }
}

json

除非显式设置, Vega-Lite自动生成axes,legends,scales等信息;
支持很多数据转换操作, 后边会细讲;

单视图支持以下属性:

属性	类型	描述
mark	Mark	必需项. 指定图表类型, 可选`bar, circle, square, tick, line, area, point, rule, geoshape, text`, 也可以指定一个对象, 详细控制mark的属性细节。
encoding	Encoding	作图元素和属性的键值对映射
width	Number/String/Object	图的宽度: 1. 如果x轴是连续值, width应该是一个数值; 2. 如果x轴是离散值或没有x轴, width可以是数值, 也可以是一个`{step:number}`对象, 用以定义每个离散元素的宽度 3. 设置成`container`, 让width可以响应式变动.
height	Number/String/Object	类似于width, 作用于y轴
view	ViewBackground	定义view背景的对象, 默认是none(透明)
projection	Projection	图像的投射, 如果是mark是`geoshape`, 会应用`shape`路径, 如果是其他marks, 会投射到`latitude`和`longitude`

背景

background属性设置整个图的背景色, view中的一堆属性设置作图区的边框和背景:

属性	类型	描述
style	`String/String[]`	应用预设主题
cornerRadius	Number/ExprRef	圆角矩形或弧线的弧度(像素)
cursor	String	鼠标指针属性, 参考CSS cursor type
fill	Color/Null/ExprRef	填充色
fillOpacity	Number/ExprRef	填充透明度[0,1]
opacity	Number/ExprRef	整体透明度[0,1]
stroke	Color/Null/ExprRef	笔画颜色, 默认: "#ddd"
strokeCap	String/ExprRef	画笔末端属性: `butt, round, square`, 三者差别可参考这里
strokeDash	Number/ExprRef	数组, 表示虚线
strokeDashOffset	Number/ExprRef	虚线偏移量(像素)
strokeJoin	String/ExprRef	画笔拼接方法, `miter, round, bevel`, 三种的差别可参考这里
strokeMiterLimit	Number/ExprRef	miter方法中, 配置join的倾斜等级
StrokeOpacity	Number/ExprRef	画笔透明度[0,1]
strokeWidth	Number/ExprRef	画笔宽度,像素

示例图:

{
  "background": "#FFDD",
  "view": {"fill": "#92388850", "stroke":"#923","strokeWidth":4},
  "data": {"url": "/assets/data/cars.json"},
  "mark": "point",
  "encoding": {
    "x": {"field": "Horsepower", "type": "quantitative"},
    "y": {"field": "Miles_per_Gallon", "type": "quantitative"}
  }
}

视图配置项

也可以通过在config对象中指定view的属性, 来更改样式. config中view的配置项除了支持所有背景中的属性外, 还提供如下属性:

属性	类型	描述
continuousWidth	Number	连续变量的X轴的默认宽度
continuousHeight	Number	连续变量的Y轴的默认高度
discreteWidth	Number/Object	离散变量的X轴的默认宽度, 可以是数字, 也可以是`{step:number}`对象
discreteHeight	Number/Object	离散变量的Y轴的默认宽度, 可以是数字, 也可以是`{step:number}`对象
step	Number	离散X/Y的默认step size

举个栗子:

{
    "data": { "url": "/assets/data/population.json"},
    "transform": [{
        "filter": "datum.year == 2000"
    }],
    "mark": "bar",
    "encoding": {
        "x": {
        "aggregate": "sum", "field": "people", "title": "population"
        }
    },
    "config": {"view": {"step": 15}}
}

标题`title`

title给图表添加一个标题, tilte有如下可选属性:

属性	类型	描述
text	Text/ExprRef	必需, 文本
align	String	对齐, `left, center, right`
anchor	Null/String	标题的锚点, `start, middle, end`, 默认是`middle`
angle	Number/ExprRef	角度
baseline	String	基准线, `alphabetic, top, middle, bottom, line-top, line-botton`, 默认是`alphabetic`
color	Null/Color/ExprRef	标题的文字颜色
dx	Number/ExprRef	Delta按列取子集
dy	Number/ExprRef	Delta按行取子集
font	String/ExprRef	字体
fontSize	Number/ExprRef	大小
fontStyle	String/ExprRef	文本类型
...	...	...

宽/高

Single View和layer有width和height属性, 用来设置作图区域的宽高, 如果想设置图的整体大小, 可以用autosize属性。

如果顶层的宽高没设置, Single View的宽高由config决定;
默认宽是200(连续)或20(离散)

用数值固定宽高:

{
    "width": 200,
    "height": 200,
    "data": {"url": "/assets/data/cars.json"},
    "mark": "bar",
    "encoding":{
        "x": {"field": "Origin"},
        "y": {"aggregate": "count"}
    }
}

固定宽高的坏处就是不能自适应, 可以用container指示宽高由上游容器制定, 如果此时上游的容器(比如一个<div>)没有设置宽高, 则还是用config中的默认值

对于多分组的离散变量, 宽高的step设置自动应用于最细分的每个分组: 如下例子中, step设置每个bar的宽度是10px:

{
    "data": {
        "values": [
        {"category":"A", "group": "x", "value":0.1},
        {"category":"A", "group": "y", "value":0.6},
        {"category":"A", "group": "z", "value":0.9},
        {"category":"B", "group": "x", "value":0.7},
        {"category":"B", "group": "y", "value":0.2},
        {"category":"B", "group": "z", "value":1.1},
        {"category":"C", "group": "x", "value":0.6},
        {"category":"C", "group": "y", "value":0.1},
        {"category":"C", "group": "z", "value":0.2}
        ]
    },
    "width": {"step": 10},
    "mark": "bar",
    "encoding": {
        "x": {"field": "category"},
        "y": {
        "field": "value", "type": "quantitative",
        "axis": {"title": "population", "grid": false}
        },
        "xOffset": {"field": "group"},
        "color": {"field": "group"}
}

如果想对每个大分组(上图x轴中A, B, C)设置宽高, 添加"for": "position"即可, 比如下图中设置三个分组的总宽为40px:

{
    "data": {
        "values": [
        {"category":"A", "group": "x", "value":0.1},
        {"category":"A", "group": "y", "value":0.6},
        {"category":"A", "group": "z", "value":0.9},
        {"category":"B", "group": "x", "value":0.7},
        {"category":"B", "group": "y", "value":0.2},
        {"category":"B", "group": "z", "value":1.1},
        {"category":"C", "group": "x", "value":0.6},
        {"category":"C", "group": "y", "value":0.1},
        {"category":"C", "group": "z", "value":0.2}
        ]
    },
    "width": {"step": 40, "for":"position"},
    "mark": "bar",
    "encoding": {
        "x": {"field": "category"},
        "y": {
        "field": "value", "type": "quantitative",
        "axis": {"title": "population", "grid": false}
        },
        "xOffset": {"field": "group"},
        "color": {"field": "group"}
}

`autosize`自适应宽高

autosize支持如下属性:

属性	类型	描述
type	String	可选`pad, fit, fit-x, fit-y, none`
resize	Boolean	是否每次更新图形后重新计算autosize, 默认`false`
contains	String	如何计算size,可选`content, padding`. `content`(默认)=>先计算宽高再加padding信息; `padding` => 把padding信息也加到宽高设置中

autosize的type参数介绍:

none: 不自动设置大小
pad: 默认值, 自动设置大小使得所有作图区域可以全部展示, 所以最终成图很可能会超过设置的宽高一些
fit: 强制要求整个作图区域缩放适配到设置的宽高值, 如果图之外的附属信息, 比如刻度, 坐标, 图注等占幅特别大的话, 设置这个可能会导致真正作图区域变得很小。
fit-x和fit-y: 对单个维度应用fit

📘 `fit`的局限

fit只适用于Single View和layout
离散变量的step比fit的优先级高

示例:

{
  "width": 300,
  "autosize": {
    "type": "fit",
    "contains": "padding"
  },
  "data": {
    "values": [
      {"a": "A", "b": 28}, {"a": "B", "b": 55}, {"a": "C", "b": 43},
      {"a": "D", "b": 91}, {"a": "E", "b": 81}, {"a": "F", "b": 53},
      {"a": "G", "b": 19}, {"a": "H", "b": 87}, {"a": "I", "b": 52}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "a", "type": "ordinal"},
    "y": {"field": "b", "type": "quantitative"}
  }
}

多图中的宽高

生成分面多图时, 可以设置每个子图的宽高, 从而设置多图宽高:

{
  "data": {"url": "data/movies.json"},
  "facet": {"column": {"field": "MPAA Rating"}},
  "spec": {
    "width": 75,
    "height": 75,
    "mark": "point",
    "encoding": {
      "x": {"field": "Worldwide Gross", "type": "quantitative"},
      "y": {"field": "US DVD Sales", "type": "quantitative"}
    }
  }
}

用column和row生成多图, 也是一样的逻辑。以下代码会产生跟上图一样的图:

{
  "width": 75,
  "height": 75,
  "data": {"url": "data/movies.json"},
  "mark": "point",
  "encoding": {
    "column": {"field": "MPAA Rating"}, // <-- 用column分面
    "x": {"field": "Worldwide Gross", "type": "quantitative"},
    "y": {"field": "US DVD Sales", "type": "quantitative"}
  }
}